<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual describes GNU Stow version 2.3.1
(28 July 2019), a program for managing farms of symbolic links.

Software and documentation is copyrighted by the following:

(C) 1993, 1994, 1995, 1996 Bob Glickstein <bobg+stow@zanshin.com>


(C) 2000, 2001 Guillaume Morin <gmorin@gnu.org>


(C) 2007 Kahlil (Kal) Hodgson <kahlil@internode.on.net>


(C) 2011 Adam Spiers <stow@adamspiers.org>

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.


Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled "GNU General Public License" is included with the
modified manual, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation. -->
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Introduction (Stow)</title>

<meta name="description" content="Introduction (Stow)">
<meta name="keywords" content="Introduction (Stow)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index.html#Index" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Terminology.html#Terminology" rel="next" title="Terminology">
<link href="index.html#Top" rel="prev" title="Top">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="Introduction"></a>
<div class="header">
<p>
Next: <a href="Terminology.html#Terminology" accesskey="n" rel="next">Terminology</a>, Previous: <a href="index.html#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Introduction-1"></a>
<h2 class="chapter">1 Introduction</h2>

<p>GNU Stow is a symlink farm manager which takes distinct sets of
software and/or data located in separate directories on the
filesystem, and makes them all appear to be installed in a single
directory tree.
</p>
<p>Originally Stow was born to address the need to administer, upgrade,
install, and remove files in independent software packages without
confusing them with other files sharing the same file system space.
For instance, many years ago it used to be common to compile programs
such as Perl and Emacs from source and install them in
<samp>/usr/local</samp>.  When one does so, one winds up with the following
files<a name="DOCF1" href="#FOOT1"><sup>1</sup></a> in
<samp>/usr/local/man/man1</samp>:
</p>
<div class="example">
<pre class="example">a2p.1
ctags.1
emacs.1
etags.1
h2ph.1
perl.1
s2p.1
</pre></div>

<p>Now suppose it&rsquo;s time to uninstall Perl.  Which man pages
get removed?  Obviously <samp>perl.1</samp> is one of them, but it should not
be the administrator&rsquo;s responsibility to memorize the ownership of
individual files by separate packages.
</p>
<p>The approach used by Stow is to install each package into its own
tree, then use symbolic links to make it appear as though the files are
installed in the common tree.  Administration can be performed in the
package&rsquo;s private tree in isolation from clutter from other packages.
Stow can then be used to update the symbolic links.  The structure
of each private tree should reflect the desired structure in the common
tree; i.e. (in the typical case) there should be a <samp>bin</samp> directory
containing executables, a <samp>man/man1</samp> directory containing section 1
man pages, and so on.
</p>
<p>While this is useful for keeping track of system-wide and per-user
installations of software built from source, in more recent times
software packages are often managed by more sophisticated package
management software such as
<a href="https://en.wikipedia.org/wiki/Rpm_(software)"><code>rpm</code></a>,
<a href="https://en.wikipedia.org/wiki/Dpkg"><code>dpkg</code></a>, and
<a href="https://en.wikipedia.org/wiki/Nix_package_manager">Nix</a> /
<a href="https://en.wikipedia.org/wiki/GNU_Guix">GNU Guix</a>, or
language-native package managers such as
<a href="https://en.wikipedia.org/wiki/RubyGems">Ruby&rsquo;s <code>gem</code></a>,
<a href="https://en.wikipedia.org/wiki/Pip_(package_manager)">Python&rsquo;s
<code>pip</code></a>, <a href="https://en.wikipedia.org/wiki/Npm_(software)">Javascript&rsquo;s <code>npm</code></a>, and so on.
</p>
<p>However Stow is still used not only for software package management,
but also for other purposes, such as facilitating a more controlled
approach to management of configuration files in the user&rsquo;s home
directory<a name="DOCF2" href="#FOOT2"><sup>2</sup></a>,
especially when coupled with version control
systems<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>.
</p>
<p>Stow was inspired by Carnegie Mellon&rsquo;s Depot program, but is
substantially simpler and safer.  Whereas Depot required database
files to keep things in sync, Stow stores no extra state between runs,
so there&rsquo;s no danger (as there was in Depot) of mangling directories
when file hierarchies don&rsquo;t match the database.  Also unlike Depot,
Stow will never delete any files, directories, or links that appear in
a Stow directory (e.g., <samp>/usr/local/stow/emacs</samp>), so it&rsquo;s always
possible to rebuild the target tree (e.g., <samp>/usr/local</samp>).
</p>
<p>Stow is implemented as a combination of a Perl script providing a CLI
interface, and a backend Perl module which does most of the work.
</p>
<p>For information about the latest version of Stow, you can refer to
<a href="http://www.gnu.org/software/stow/">http://www.gnu.org/software/stow/</a>.
</p>

<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
<p>As of Perl 4.036 and Emacs 19.22.  These are now
ancient releases but the example still holds valid.</p>
<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
<p><a href="http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html">http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html</a></p>
<h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
<p><a href="http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html">http://lists.gnu.org/archive/html/info-stow/2011-12/msg00000.html</a></p>
</div>
<hr>
<div class="header">
<p>
Next: <a href="Terminology.html#Terminology" accesskey="n" rel="next">Terminology</a>, Previous: <a href="index.html#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html#Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
